This is the documentation to detail out the design of the state representation interface between the GUI application and the instrument itself. This interface will allow the GUI (and other applications) to get information about the current state of the various components of the ESP.

Some details about the interface:

1. The ESP application (server) shall listen on a fixed TCP socket.
2. Any number clients can connect to this socket, each thereby opening a separate, private, bidirectional, ASCII connection to the ESP server.
3. The server will respond to the following client commands:
   1. List all available states
      1. Each state is identified by a short symbolic (ASCII) name.
   2. Retrieve metadata for subset of those states and subscribe to them
      1. Elements in lists of states are separated with commas
         1. There is no whitespace between list elements
      2. The order of the elements in state lists determine the ordering in reporting state vectors described below.
      3. Metadata shall include:
         1. Description e.g. Storage carousel
         2. sprintf format string e.g. %.2fml
         3. range (min and max expected values)

            hardware failures may cause reported values to be out of range

         4. map of sybolically labeled positions, each on a line of this format:

              <numeric position>,<symbolic label>,<alias1>,<alias2>,<aliasN>
            

   3. Subscribe to updates on (only) the specified states

      This limits subsequent state updates to just those listed by their symbolic names. This message also determines the ordering of states in vectors described below.

   4. Refresh all subscribed states

      All the subscribed states are sent to the client in the order in which they were listed in the most recent subscribe or retrieve metadata message. <timestamp? seconds since epoch??> <new value[0]>{,optional additional info like current, pwm%, etc. (may be ignored)} <new value[1]>{,optional additional info like current, pwm%, etc.} ... <new value[n-1]>{,optional additional info like current, pwm%, etc.} where n is the number of states subscribed. This establishes a baseline from which subsequent state changes are reported.

   5. Request C more changed state updates at maximum rate one per t tenths of seconds.

      The client tells the server it is ready to receive C more state change responses and that the server may emit these at a rate no faster than one every t tenths of a second. A client wishing to continuously monitor state should send a new request shortly before the last update (as allowed by the previous request) has been received. If C is kept small (say 10 or so), this mechanism will ensure that update messages don't back up on the networking queue, while avoiding paying any network latency penalty. (Similar to TCP's sliding window mechanism) The client can stop updates by requesting 0 more at some arbitrary rate. Only those states whose values changed since the last update will be sent Format will be a list of lines, each of the form: <index>,<new value>{,optional additional info like current, pwm%, etc.} where: index = an integer from 0 to n-1 where n is the number of subscribed states new value = number conforming to the state's sprintf format string (note that the unit suffix will be omitted, i.e. 0.2 not 0.2ml)

      Notes for Brent Normally, all I2C messages between the Linux host and the dwarves are logged. However, this protocol will require continuous polling of all the subscribed dwarves' raw positions. Nothing else currently does anything like this (by design! . Clearly, such messages should not be logged. Further, it may be necessary to add an I2C message to the dwarf firmware that queries raw position only. The existing full status poll message returns lots of extraneous engineering info like velocity, electrical current, etc.

2-Feb-2011(weekly gui meeting). There will be a keep-alive message at some interval for the case where nothing is changing in the subscribed-to states - so the dashboard can know when coms are lost with the esp. Also, still need to resolve the 'raw units' vs. 'engineering units' question. Dashboard will need to get to engineering units somehow. Brent still wants to think this thru a bit more. 3-Feb-2011 Roman pointed out that we also need to know at the dashboard when the the esp is locked up with an error. Rich discussed briefly with Brent. While it may not strictly be 'state',  it is important info to communicate to users via the dashboard.  Brent suggested perhaps a second socket would have the error messages (question... how would we notify the dashboard when error condition had cleared?). Posted by rich at Feb 03, 2011 09:16

Wanted to capture here from earlier GUI meeting discussions: ESP on-board will track and provide additional state items for things like number of pucks in a tube, capacity and current volume estimate for reagent & waste bags etc.  These items can only really be inferred by the ESP as it is initialized and run as there is no actually sensor measuring these 'states'.   Posted by rich at Feb 03, 2011 09:31